home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / epb233.zip / EPB233.DOC < prev    next >
Text File  |  1992-07-25  |  9KB  |  215 lines
  1.                        ED'S PASCAL BEAUTIFIER (EPB)
  2.                        Copyright 1992 By Edward Lee
  3.                                25 July 1992
  4.  
  5.  
  6.  
  7. EPB  v2.32  formats Pascal  source code  in a  consistent form,  with fully 
  8. automatic indentation.  The resulting source code  can be  well compressed. 
  9. EPB generally preserves existing line breaks but conditionally inserts line 
  10. breaks  after  semicolons and  the keywords  BEGIN, DO,  ELSE, OF,  RECORD, 
  11. REPEAT, and THEN.  EPB does not check for syntax errors,  so you  must rely 
  12. on yourself or on the compiler for syntax checking.  EPB can, however, help 
  13. you  to  see programming  or typing  errors that  you may  have made.   For 
  14. example, if you forget to close a comment, EPB will  not format  any source 
  15. code that comes after the beginning  of the  comment until  the comment  is 
  16. closed.  This means that if your code  is formatted  in the  default upper- 
  17. case mode, then you can toggle  the case  of the  Pascal keywords  with the 
  18. -(m)ixed case switch to see if any code  is being  commented out.   EPB can 
  19. also help you to see unintended semantics in nested Pascal code, especially 
  20. in  nested  IF  THEN  ELSE constructs.   All user-declared  identifiers for 
  21. constants, data  types, variables,  labels, procedures,  and functions  are 
  22. capitalized to the way they first appear in the Pascal source code.  EPB is 
  23. a  tool  with  many  features  that  will help  make it  easier for  you to 
  24. comprehend  and  to  maintain  Pascal  source  code,  whether  you  are  an 
  25. experienced or a beginning Pascal programmer.
  26.  
  27. Examples of  EPB invocations are provided at the end of this file.
  28.  
  29. EPB requires over 256 KB of free conventional memory in order to  run.  The 
  30. maximum length of a user-declared identifier can be  255 characters,  which 
  31. exceeds the Turbo Pascal  v4.0 standard.   The Turbo  Pascal v4.0  compiler 
  32. still only  recognizes  the  first  63  characters  of  an   identifier  as 
  33. significant, however.  The maximum indentation depth is arbitrarily  set at 
  34. 255  indentation  levels.   Statements  nested that  deeply would  probably 
  35. exceed Turbo Pascal v4.0's maximum line  length.  If  one of  your programs 
  36. ever  exceeds  the  maximum  line length  with deeply  nested IF  THEN ELSE 
  37. constructs, then you may want to change the ElseIndent constant to 0 (zero) 
  38. in the EPB.PAS source code that is provided and recompile EPB.
  39.  
  40. If your machine crashes or locks up while using NCACHE  v6.0 or  some other 
  41. resident program during the execution of  EPB, your  source file  will most 
  42. likely be saved as a "*.BAK" backup file or as the original file.  If  such 
  43. an unfortunate event occurs, regain control  over your  computer and  check 
  44. the file size of your Pascal source code to make sure that the size  is not 
  45. 0 (zero).  If the file size is zero, then look  for the  program's filename 
  46. with the ".BAK" file name extension.  If that  file is  also gone,  you may 
  47. have to resort to using a file recovery utility such as the  ones found  in 
  48. Norton Utilities.  I recommend that you do NOT use NCACHE v6.0 with  any of 
  49. your  important  or high  input/output performance  programs.  If  you have 
  50. NCACHE v6.0, you might want to consider getting  a more  recent version  or 
  51. another disk caching program.
  52.  
  53. EPB is continually being improved.  If  you have  any specific  suggestions 
  54. for   improving   EPB,   you   can  contact   the  author   via  email   as 
  55. edlee@chinet.chi.il.us on Usenet.
  56.  
  57.  
  58.  
  59. INVOCATION EXAMPLES
  60.  
  61.  1. The following three invocations of EPB are equivalent to each other:
  62.  
  63.          epb file
  64.  
  65.          epb file.pas
  66.  
  67.          epb file.pas file.pas
  68.  
  69.     In the above examples,  the original  file is  renamed to  *.BAK before 
  70.     being used as the input file.  Any one of the invocations is equivalent 
  71.     to the following two commands in sequence at the MSDOS prompt:
  72.  
  73.          rename file.pas file.bak
  74.          epb    file.bak file.pas
  75.  
  76.     I generally recommend the first invocation, "epb file", since it is the 
  77.     simplest and since it resembles a compilation such as, "tpc file".
  78.  
  79.  
  80.  2. Display a help screen:
  81.  
  82.          epb
  83.  
  84.  
  85.  3. Format file.pas with (-m)ixed case Pascal identifiers:
  86.  
  87.          epb -m file
  88.  
  89.     The "-m" switch shuts off the default capitalization of (Turbo)  Pascal 
  90.     keywords.
  91.  
  92.  
  93.  4. (-S)ubstitute all of the identifiers in file.pas  that match  "xx" with 
  94.     "MoreDescriptiveIdentifier":
  95.  
  96.          epb file -s xx MoreDescriptiveIdentifier
  97.  
  98.             or
  99.  
  100.          epb -s xx MoreDescriptiveIdentifier file
  101.  
  102.     I often use short  identifiers when  developing code  to save  time and 
  103.     later want to use more descriptive names for  the sake  of readability.  
  104.     During identifier substitution, comments and literal  strings are  left 
  105.     alone by EPB, as well as  substrings in  larger identifiers.   Starting 
  106.     with EPB v2.33, the letter E in real constants such as 1.0e-10  is also 
  107.     ignored as well as the letters in hexadecimal constants such  as $fe00.  
  108.     This  substitution  option  is  superior  to  many editors'  search and 
  109.     replace  features,  since  EPB  takes some  of the  Pascal syntax  into 
  110.     account.  If you also want to change some  identifiers that  are within 
  111.     comments,  you  will  have  to  change  those identifiers  without EPB, 
  112.     because EPB never alters the content of comments.
  113.  
  114.  
  115.  5. Accept input data  from some  other program  via the  standard (-i)nput 
  116.     stream, format it, and output the formatted data to outfile.pas:
  117.  
  118.          producer | epb -i outfile
  119.  
  120.     A PRODUCER  is any  program that  outputs data  to the  standard output 
  121.     stream.  Any program that  displays data  on the  screen is  a producer 
  122.     unless it is directly writing to the screen,  bypassing the  BIOS.  One 
  123.     program's output  stream can  be another  program's input  stream.  Any 
  124.     program that accepts data from the standard input stream is known as  a 
  125.     consumer.  EPB acts as a CONSUMER in the above invocation.
  126.  
  127.  
  128.  6. Accept  input  data  from  another  program  via the  standard (-i)nput 
  129.     stream, process it, and send the output data to some other program  via 
  130.     the standard (-o)utput stream:
  131.  
  132.          producer | epb -io | consumer
  133.  
  134.    Programs like MORE or Buerg's LIST /S are possible consumers.
  135.  
  136.  
  137.  7. Get input data  from the  file "infile.pas",  process it,  and put  the 
  138.     output data in a file named "outfile.pas", not changing the contents of 
  139.     "infile.pas":
  140.  
  141.          epb infile outfile
  142.  
  143.  
  144.  8. Get input data from file.pas, process it, and send  the output  data to 
  145.     the standard (o)utput stream which, in this case, leads to the screen:
  146.  
  147.          epb file -o
  148.  
  149.     When data is sent to the  standard output  stream with  no output  pipe 
  150.     ("|"), it is conventional  in both  MSDOS and  Unix for  the output  to 
  151.     appear on the display device.
  152.  
  153.  
  154.  9. Get the input data from the standard (-i)nput stream  (the keyboard  in 
  155.     this case), format the data,  and output  the data  to the  standard
  156.     (-o)utput stream (the screen in this case):
  157.  
  158.          epb -io
  159.  
  160.     This invocation is useful for determining how EPB  will format  a small 
  161.     code segment that is entered from the keyboard.  It is  conventional in 
  162.     both MSDOS and Unix for standard input data to come  from the  keyboard 
  163.     when no input pipe ("|") is specified.  You can terminate your input on 
  164.     a separate line by pressing [Ctrl]-Z or the [F6] function key, followed 
  165.     by pressing the [Enter] or [Return] key. 
  166.  
  167.  
  168. 10. Shut off the output of parentheses comments:
  169.  
  170.          epb -p file
  171.  
  172.     This is a preprocessor-like feature of  EPB that  I am  considering for 
  173.     removal.  Let me know if you think that this option is worth keeping.
  174.  
  175.  
  176. 11. Shut off the output of bracket comments:
  177.  
  178.          epb -b file
  179.  
  180.     This is exactly like example 10, except that  bracket comments,  {...}, 
  181.     are deleted instead of parentheses comments, (* ... *).
  182.  
  183.  
  184. 12. Examples 10 and 11 can be combined:
  185.  
  186.          epb -bp file
  187.  
  188.     To shut off the output of all comments.
  189.  
  190.  
  191.  
  192. ACKNOWLEDGMENTS
  193.  
  194.  
  195. EPB is influenced by  the work  of AT&T  Unix authors  in its  naming (e.g.  
  196. John's Own Version of Emacs, JOVE) and in  the structure  of its  interface 
  197. (e.g.  '-'  as the switch character.).
  198.  
  199. In the EPB versions past v1.5,  some users  have suggested  improvements to 
  200. the  program.   My  thanks  go out  to them  for helping  to make  EPB more 
  201. interesting.
  202.  
  203. EPB is intended to be a free program, a gift to the  other programmers  out 
  204. there, so if you paid money  for this,  you may  have unnecessarily  parted 
  205. with some of your money.  All rights to EPB are reserved by the author, and 
  206. EPB is provided without warranty, though it is unlikely that you will  ever 
  207. encounter any serious problems with this program.
  208.  
  209.  
  210. -Ed L
  211. edlee@chinet.chi.il.us
  212.  
  213. Unofficial member of a nonexistent group, S.T.A.T.S. (Some Take Acronyms 
  214. Too Seriously).
  215.